Summary

When assigning to a constant array with a union of constant string keys (e.g., 'a'|'b') or a finite integer range (e.g., int<1,5>), PHPStan previously degraded to a general ArrayType, losing the constant array shape information. This change produces a union of constant arrays instead, preserving precise type information.

For example, given @param array{foo: int} $a and @param int<1,5> $intRange:

$a[$intRange] = 256;
// Before: non-empty-array<'foo'|int<1, 5>, int>
// After:  array{foo: int, 1: 256}|array{foo: int, 2: 256}|array{foo: int, 3: 256}|array{foo: int, 4: 256}|array{foo: int, 5: 256}

Changes

• src/Type/Constant/ConstantArrayType.php:
  • Modified setOffsetValueType() to detect when the offset type can be expanded to a finite set of constant keys with at least one new key, and produce a union of constant arrays
  • Added resolveFiniteScalarKeyTypes() private helper method that resolves offset types to individual constant key types from string unions and integer ranges
  • Limited expansion to CHUNK_FINITE_TYPES_LIMIT (5) new keys to avoid combinatorial explosion
  • Only expands string constant unions and IntegerRangeType (not integer constant unions like 0|1 which typically come from loop fixpoint analysis)
• tests/PHPStan/Analyser/nsrt/set-constant-union-offset-on-constant-array.php: New regression test covering string union keys, integer range keys, infinite ranges, and existing keys
• tests/PHPStan/Analyser/nsrt/constant-array-type-set.php: Updated test expectation for int<0, 4> offset on 3-element array to reflect more precise union result
• CLAUDE.md: Added documentation about the new union expansion behavior

Root cause

ConstantArrayTypeBuilder::setOffsetValueType() handles non-constant offset types by expanding them to constant scalars and checking if all match existing keys. When some keys were new (not in the array), it fell through to a degradation path that produced a general ArrayType. The fix intercepts this at the ConstantArrayType::setOffsetValueType() level, creating a union of arrays for each possible key before the builder can degrade.

The expansion is carefully limited to avoid regressions:

• Only string constant unions and IntegerRangeType trigger expansion (not integer constant unions which are common in loop analysis)
• At most CHUNK_FINITE_TYPES_LIMIT (5) new keys are expanded
• When all keys already exist in the array, the builder handles it directly without expansion

Test

Added tests/PHPStan/Analyser/nsrt/set-constant-union-offset-on-constant-array.php with four test cases:

1. doFoo: String union offset 'a'|'b' on array{foo: int} → union of two constant arrays
2. doBar: Integer range int<1,5> on array{foo: int} → union of five constant arrays
3. doInfiniteRange: Infinite range int<0, max> → falls back to general array (no expansion)
4. doExistingKeys: Range int<0,1> on array{0: 'a', 1: 'b'} → handled by builder directly

Fixes phpstan/phpstan#14129

Closes phpstan/phpstan#9907